home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / python / pythnlbn.lha / python-lib.info-2 (.txt) < prev    next >
GNU Info File  |  1993-07-29  |  50KB  |  926 lines
  1. This is Info file python-lib.info, produced by Makeinfo-1.43 from the
  2. input file @out.texi.
  3. This file describes the built-in types, exceptions and functions and
  4. the standard modules that come with the Python system.  It assumes
  5. basic knowledge about the Python language.  For an informal
  6. introduction to the language, see the Python Tutorial.  The Python
  7. Reference Manual gives a more formal definition of the language. 
  8. (These manuals are not yet available in INFO or Texinfo format.)
  9. Copyright (C) 1991, 1992, 1993 by Stichting Mathematisch Centrum,
  10. Amsterdam, The Netherlands.
  11. All Rights Reserved
  12. Permission to use, copy, modify, and distribute this software and its
  13. documentation for any purpose and without fee is hereby granted,
  14. provided that the above copyright notice appear in all copies and that
  15. both that copyright notice and this permission notice appear in
  16. supporting documentation, and that the names of Stichting Mathematisch
  17. Centrum or CWI not be used in advertising or publicity pertaining to
  18. distribution of the software without specific, written prior
  19. permission.
  20. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
  21. THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22. FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
  23. FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  24. WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  25. ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  26. OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  27. File: python-lib.info,  Node: math,  Next: time,  Prev: __main__,  Up: Built-in Modules
  28. Built-in Module `math'
  29. ======================
  30. This module is always available.  It provides access to the
  31. mathematical functions defined by the C standard.  They are:
  32.  -- function of module math: acos (X)
  33.  -- function of module math: asin (X)
  34.  -- function of module math: atan (X)
  35.  -- function of module math: atan2 (X, Y)
  36.  -- function of module math: ceil (X)
  37.  -- function of module math: cos (X)
  38.  -- function of module math: cosh (X)
  39.  -- function of module math: exp (X)
  40.  -- function of module math: fabs (X)
  41.  -- function of module math: floor (X)
  42.  -- function of module math: fmod (X, Y)
  43.  -- function of module math: frexp (X)
  44.  -- function of module math: ldexp (X, Y)
  45.  -- function of module math: log (X)
  46.  -- function of module math: log10 (X)
  47.  -- function of module math: modf (X)
  48.  -- function of module math: pow (X, Y)
  49.  -- function of module math: sin (X)
  50.  -- function of module math: sinh (X)
  51.  -- function of module math: sqrt (X)
  52.  -- function of module math: tan (X)
  53.  -- function of module math: tanh (X)
  54. Note that `frexp' and `modf' have a different call/return pattern than
  55. their C equivalents: they take a single argument and return a pair of
  56. values, rather than returning their second return value through an
  57. `output parameter' (there is no such thing in Python).
  58. The module also defines two mathematical constants:
  59.  -- data of module math: pi
  60.  -- data of module math: e
  61. File: python-lib.info,  Node: time,  Next: regex,  Prev: math,  Up: Built-in Modules
  62. Built-in Module `time'
  63. ======================
  64. This module provides various time-related functions.  It is always
  65. available.  (On some systems, not all functions may exist; e.g. the
  66. "milli" variants can't always be implemented.)
  67. An explanation of some terminology and conventions is in order.
  68.    * The "epoch" is the point where the time starts.  On January 1st
  69.      that year, at 0 hours, the "time since the epoch" is zero.
  70.    * UTC is Coordinated Universal Time (formerly known as Greenwich
  71.      Mean Time).  The acronym UTC is not a mistake but a compromise
  72.      between English and French.
  73.    * DST is Daylight Saving Time, an adjustment of the timezone by
  74.      (usually) one hour during part of the year.  DST rules are magic
  75.      (determined by local law) and can change from year to year.  The C
  76.      library has a table containing the local rules (often it is read
  77.      from a system file for flexibility) and is the only source of
  78.      True Wisdom in this respect.
  79.    * The precision of the various real-time functions may be less than
  80.      suggested by the units in which their value or argument is
  81.      expressed.  E.g. on most UNIX systems, the clock "ticks" only
  82.      every 1/50th or 1/100th of a second, and on the Mac, it ticks 60
  83.      times a second.
  84. Functions and data items are:
  85.  -- data of module time: altzone
  86.      The offset of the local DST timezone, in seconds west of the 0th
  87.      meridian, if one is defined.  Only use this if `daylight' is
  88.      nonzero.
  89.  -- data of module time: daylight
  90.      Nonzero if a DST timezone is defined.
  91.  -- function of module time: gmtime (SECS)
  92.      Convert a time expressed in seconds since the epoch to a tuple of
  93.      9 integers, in UTC: year (e.g. 1993), month (1-12), day (1-31),
  94.      hour (0-23), minute (0-59), second (0-59), weekday (0-6, monday
  95.      is 0), julian day (1-366), dst flag (always zero).  Fractions of
  96.      a second are ignored.  Note subtle differences with the C
  97.      function of this name.
  98.  -- function of module time: localtime (SECS)
  99.      Like `gmtime' but converts to local time.  The dst flag is set to
  100.      1 when DST applies to the given time.
  101.  -- function of module time: millisleep (MSECS)
  102.      Suspend execution for the given number of milliseconds. 
  103.      (Obsolete, you can now use use `sleep' with a floating point
  104.      argument.)
  105.  -- function of module time: millitimer ()
  106.      Return the number of milliseconds of real time elapsed since some
  107.      point in the past that is fixed per execution of the python
  108.      interpreter (but may change in each following run).  The return
  109.      value may be negative, and it may wrap around.
  110.  -- function of module time: mktime (TUPLE)
  111.      This is the inverse function of `localtime'.  Its argument is the
  112.      full 9-tuple (since the dst flag is needed).  It returns an
  113.      integer.
  114.  -- function of module time: sleep (SECS)
  115.      Suspend execution for the given number of seconds.  The argument
  116.      may be a floating point number to indicate a more precise sleep
  117.      time.
  118.  -- function of module time: time ()
  119.      Return the time as a floating point number expressed in seconds
  120.      since the epoch, in UTC.  Note that even though the time is
  121.      always returned as a floating point number, not all systems
  122.      provide time with a better precision than 1 second.  An
  123.      alternative for measuring precise intervals is `millitimer'.
  124.  -- data of module time: timezone
  125.      The offset of the local (non-DST) timezone, in seconds west of
  126.      the 0th meridian (i.e. negative in most of Western Europe,
  127.      positive in the US, zero in the UK).
  128.  -- data of module time: tzname
  129.      A tuple of two strings: the first is the name of the local non-DST
  130.      timezone, the second is the name of the local DST timezone.  If
  131.      no DST timezone is defined, the second string should not be used.
  132. File: python-lib.info,  Node: regex,  Next: marshal,  Prev: time,  Up: Built-in Modules
  133. Built-in Module `regex'
  134. =======================
  135. This module provides regular expression matching operations similar to
  136. those found in Emacs.  It is always available.
  137. By default the patterns are Emacs-style regular expressions; there is
  138. a way to change the syntax to match that of several well-known UNIX
  139. utilities.
  140. This module is 8-bit clean: both patterns and strings may contain null
  141. bytes and characters whose high bit is set.
  142. *Please note:* There is a little-known fact about Python string
  143. literals which means that you don't usually have to worry about
  144. doubling backslashes, even though they are used to escape special
  145. characters in string literals as well as in regular expressions.  This
  146. is because Python doesn't remove backslashes from string literals if
  147. they are followed by an unrecognized escape character.  *However*, if
  148. you want to include a literal "backslash" in a regular expression
  149. represented as a string literal, you have to *quadruple* it.  E.g.  to
  150. extract LaTeX `\section{...}' headers from a document, you can use
  151. this pattern: `'\\\\section{\(.*\)}''.
  152. The module defines these functions, and an exception:
  153.  -- function of module regex: match (PATTERN, STRING)
  154.      Return how many characters at the beginning of STRING match the
  155.      regular expression PATTERN.  Return `-1' if the string does not
  156.      match the pattern (this is different from a zero-length match!).
  157.  -- function of module regex: search (PATTERN, STRING)
  158.      Return the first position in STRING that matches the regular
  159.      expression PATTERN.  Return -1 if no position in the string
  160.      matches the pattern (this is different from a zero-length match
  161.      anywhere!).
  162.  -- function of module regex: compile (PATTERN, TRANSLATE)
  163.      Compile a regular expression pattern into a regular expression
  164.      object, which can be used for matching using its `match' and
  165.      `search' methods, described below.  The optional TRANSLATE, if
  166.      present, must be a 256-character string indicating how characters
  167.      (both of the pattern and of the strings to be matched) are
  168.      translated before comparing them; the `i'-th element of the
  169.      string gives the translation for the character with ASCII code
  170.      `i'.
  171.      The sequence
  172.           prog = regex.compile(pat)
  173.           result = prog.match(str)
  174.      is equivalent to
  175.           result = regex.match(pat, str)
  176.      but the version using `compile()' is more efficient when multiple
  177.      regular expressions are used concurrently in a single program. 
  178.      (The compiled version of the last pattern passed to
  179.      `regex.match()' or `regex.search()' is cached, so programs that
  180.      use only a single regular expression at a time needn't worry
  181.      about compiling regular expressions.)
  182.  -- function of module regex: set_syntax (FLAGS)
  183.      Set the syntax to be used by future calls to `compile', `match'
  184.      and `search'.  (Already compiled expression objects are not
  185.      affected.)  The argument is an integer which is the OR of several
  186.      flag bits.  The return value is the previous value of the syntax
  187.      flags.  Names for the flags are defined in the standard module
  188.      `regex_syntax'; read the file `regex_syntax.py' for more
  189.      information.
  190.  -- exception of module regex: error
  191.      Exception raised when a string passed to one of the functions here
  192.      is not a valid regular expression (e.g., unmatched parentheses) or
  193.      when some other error occurs during compilation or matching.  (It
  194.      is never an error if a string contains no match for a pattern.)
  195.  -- data of module regex: casefold
  196.      A string suitable to pass as TRANSLATE argument to `compile' to
  197.      map all upper case characters to their lowercase equivalents.
  198. Compiled regular expression objects support these methods:
  199.  -- Method on regex: match (STRING, POS)
  200.      Return how many characters at the beginning of STRING match the
  201.      compiled regular expression.  Return `-1' if the string does not
  202.      match the pattern (this is different from a zero-length match!).
  203.      The optional second parameter POS gives an index in the string
  204.      where the search is to start; it defaults to `0'.  This is not
  205.      completely equivalent to slicing the string; the `'^'' pattern
  206.      character matches at the real begin of the string and at positions
  207.      just after a newline, not necessarily at the index where the
  208.      search is to start.
  209.  -- Method on regex: search (STRING, POS)
  210.      Return the first position in STRING that matches the regular
  211.      expression `pattern'.  Return `-1' if no position in the string
  212.      matches the pattern (this is different from a zero-length match
  213.      anywhere!).
  214.      The optional second parameter has the same meaning as for the
  215.      `match' method.
  216.  -- Method on regex: group (INDEX, INDEX, ...)
  217.      This method is only valid when the last call to the `match' or
  218.      `search' method found a match.  It returns one or more groups of
  219.      the match.  If there is a single INDEX argument, the result is a
  220.      single string; if there are multiple arguments, the result is a
  221.      tuple with one item per argument.  If the INDEX is zero, the
  222.      corresponding return value is the entire matching string; if it
  223.      is in the inclusive range [1..9], it is the string matching the
  224.      the corresponding parenthesized group (using the default syntax,
  225.      groups are parenthesized using `
  226.      (' and `
  227.      )').  If no such group exists, the corresponding result is `None'.
  228. Compiled regular expressions support these data attributes:
  229.  -- attribute of regex: regs
  230.      When the last call to the `match' or `search' method found a
  231.      match, this is a tuple of pairs of indices corresponding to the
  232.      beginning and end of all parenthesized groups in the pattern. 
  233.      Indices are relative to the string argument passed to `match' or
  234.      `search'.  The 0-th tuple gives the beginning and end or the
  235.      whole pattern.  When the last match or search failed, this is
  236.      `None'.
  237.  -- attribute of regex: last
  238.      When the last call to the `match' or `search' method found a
  239.      match, this is the string argument passed to that method.  When
  240.      the last match or search failed, this is `None'.
  241.  -- attribute of regex: translate
  242.      This is the value of the TRANSLATE argument to `regex.compile'
  243.      that created this regular expression object.  If the TRANSLATE
  244.      argument was omitted in the `regex.compile' call, this is `None'.
  245. File: python-lib.info,  Node: marshal,  Next: struct,  Prev: regex,  Up: Built-in Modules
  246. Built-in Module `marshal'
  247. =========================
  248. This module contains functions that can read and write Python values
  249. in a binary format.  The format is specific to Python, but independent
  250. of machine architecture issues (e.g., you can write a Python value to
  251. a file on a VAX, transport the file to a Mac, and read it back there).
  252.  Details of the format not explained here; read the source if you're
  253. interested.
  254. Not all Python object types are supported; in general, only objects
  255. whose value is independent from a particular invocation of Python can
  256. be written and read by this module.  The following types are supported:
  257. `None', integers, long integers, floating point numbers, strings,
  258. tuples, lists, dictionaries, and code objects, where it should be
  259. understood that tuples, lists and dictionaries are only supported as
  260. long as the values contained therein are themselves supported; and
  261. recursive lists and dictionaries should not be written (they will
  262. cause an infinite loop).
  263. There are functions that read/write files as well as functions
  264. operating on strings.
  265. The module defines these functions:
  266.  -- function of module marshal: dump (VALUE, FILE)
  267.      Write the value on the open file.  The value must be a supported
  268.      type.  The file must be an open file object such as `sys.stdout'
  269.      or returned by `open()' or `posix.popen()'.
  270.      If the value has an unsupported type, garbage is written which
  271.      cannot be read back by `load()'.
  272.  -- function of module marshal: load (FILE)
  273.      Read one value from the open file and return it.  If no valid
  274.      value is read, raise `EOFError', `ValueError' or `TypeError'. 
  275.      The file must be an open file object.
  276.  -- function of module marshal: dumps (VALUE)
  277.      Return the string that would be written to a file by `dump(value,
  278.      file)'.  The value must be a supported type.
  279.  -- function of module marshal: loads (STRING)
  280.      Convert the string to a value.  If no valid value is found, raise
  281.      `EOFError', `ValueError' or `TypeError'.  Extra characters in the
  282.      string are ignored.
  283. File: python-lib.info,  Node: struct,  Next: array,  Prev: marshal,  Up: Built-in Modules
  284. Built-in module `struct'
  285. ========================
  286. This module performs conversions between Python values and C structs
  287. represented as Python strings.  It uses "format strings" (explained
  288. below) as a compact descriptions of the lay-out of the C structs and
  289. the intended conversion to/from Python values.
  290. The module defines the following exception and functions:
  291.  -- exception of module struct: error
  292.      Exception raised on various occasions; argument is a string
  293.      describing what is wrong.
  294.  -- function of module struct: pack (FMT, V1, V2, ...)
  295.      Return a string containing the values `V1, V2, ...' packed
  296.      according to the given format.  The arguments must match the
  297.      values required by the format exactly.
  298.  -- function of module struct: unpack (FMT, STRING)
  299.      Unpack the string (presumably packed by `pack(FMT, ...)')
  300.      according to the given format.  The result is a tuple even if it
  301.      contains exactly one item.  The string must contain exactly the
  302.      amount of data required by the format (i.e.  `len(STRING)' must
  303.      equal `calcsize(FMT)').
  304.  -- function of module struct: calcsize (FMT)
  305.      Return the size of the struct (and hence of the string)
  306.      corresponding to the given format.
  307. Format characters have the following meaning; the conversion between C
  308. and Python values should be obvious given their types:
  309. *Format*
  310.      *C*  --  *Python*
  311.      pad byte  --  no value
  312.      char  --  string of length 1
  313.      signed char  --  integer
  314.      short  --  integer
  315.      int  --  integer
  316.      long  --  integer
  317.      float  --  float
  318.      double  --  float
  319. A format character may be preceded by an integral repeat count; e.g. 
  320. the format string `'4h'' means exactly the same as `'hhhh''.
  321. C numbers are represented in the machine's native format and byte
  322. order, and properly aligned by skipping pad bytes if necessary
  323. (according to the rules used by the C compiler).
  324. Examples (all on a big-endian machine):
  325.      pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
  326.      unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)
  327.      calcsize('hhl') == 8
  328. Hint: to align the end of a structure to the alignment requirement of
  329. a particular type, end the format with the code for that type with a
  330. repeat count of zero, e.g. the format `'llh0l'' specifies two pad
  331. bytes at the end, assuming longs are aligned on 4-byte boundaries.
  332. (More format characters are planned, e.g. `'s'' for character arrays,
  333. upper case for unsigned variants, and a way to specify the byte order,
  334. which is useful for [de]constructing network packets and
  335. reading/writing portable binary file formats like TIFF and AIFF.)
  336. File: python-lib.info,  Node: array,  Prev: struct,  Up: Built-in Modules
  337. Built-in module `array'
  338. =======================
  339. This module defines a new object type which can efficiently represent
  340. an array of basic values: characters, integers, floating point
  341. numbers.  Arrays are sequence types and behave very much like lists,
  342. except that the type of objects stored in them is constrained.  The
  343. type is specified at object creation time by using a "type code",
  344. which is a single character.  The following type codes are defined:
  345. *Typecode*
  346.      *Type*  --  *Minimal size in bytes*
  347. `'c''
  348.      character  --  1
  349. `'b''
  350.      signed integer  --  1
  351. `'h''
  352.      signed integer  --  2
  353. `'l''
  354.      signed integer  --  4
  355. `'f''
  356.      floating point  --  4
  357. `'d''
  358.      floating point  --  8
  359. The actual representation of values is determined by the machine
  360. architecture (strictly spoken, by the C implementation).
  361. The module defines the following function:
  362.  -- function of module array: array (TYPECODE, INITIALIZER)
  363.      Return a new array whose items are restricted by TYPECODE, and
  364.      initialized from the optional INITIALIZER value, which must be a
  365.      list or a string.  The list or string is passed to the new array's
  366.      `fromlist()' or `fromstring()' method (see below) to add initial
  367.      items to the array.
  368. Array objects support the following data items and methods:
  369.  -- data of module array: typecode
  370.      The typecode character used to create the array.
  371.  -- data of module array: itemsize
  372.      The length in bytes of one array item in the internal
  373.      representation.
  374.  -- function of module array: append (X)
  375.      Append a new item with value X to the end of the array.
  376.  -- function of module array: insert (I, X)
  377.      Insert a new item with value X in the array before position I.
  378.  -- function of module array: read (F, N)
  379.      Read N items (as machine values) from the file object F and
  380.      append them to the end of the array.  If less than N items are
  381.      available, `EOFError' is raised, but the items that were
  382.      available are still inserted into the array.
  383.  -- function of module array: write (F)
  384.      Write all items (as machine values) to the file object F.
  385.  -- function of module array: fromstring (S)
  386.      Appends items from the string, interpreting the string as an
  387.      array of machine values (i.e. as if it had been read from a file
  388.      using the `read()' method).
  389.  -- function of module array: tostring ()
  390.      Convert the array to an array of machine values and return the
  391.      string representation (the same sequence of bytes that would be
  392.      written to a file by the `write()' method.)
  393.  -- function of module array: fromlist (LIST)
  394.      Appends items from the list.  This is equivalent to `for x in
  395.      LIST: a.append(x)' except that if there is a type error, the
  396.      array is unchanged.
  397.  -- function of module array: tolist ()
  398.      Convert the array to an ordinary list with the same items.
  399. When an array object is printed or converted to a string, it is
  400. represented as `array(TYPECODE, INITIALIZER)'.  The INITIALIZER is
  401. omitted if the array is empty, otherwise it is a string if the
  402. TYPECODE is `'c'', otherwise it is a list of numbers.  The string is
  403. guaranteed to be able to be converted back to an array with the same
  404. type and value using reverse quotes (```').  Examples:
  405.      array('l')
  406.      array('c', 'hello world')
  407.      array('l', [1, 2, 3, 4, 5])
  408.      array('d', [1.0, 2.0, 3.14])
  409. File: python-lib.info,  Node: Standard Modules,  Next: MOST OPERATING SYSTEMS,  Prev: Built-in Modules,  Up: Top
  410. Standard Modules
  411. ****************
  412. The following standard modules are defined.  They are available in one
  413. of the directories in the default module search path (try printing
  414. `sys.path' to find out the default search path.)
  415. * Menu:
  416. * string::                      Standard Module `string'
  417. * rand::                        Standard Module `rand'
  418. * whrandom::                    Standard Module `whrandom'
  419. * regsub::                      Standard Module `regsub'
  420. * os::                          Standard Module `os'
  421. File: python-lib.info,  Node: string,  Next: rand,  Up: Standard Modules
  422. Standard Module `string'
  423. ========================
  424. This module defines some constants useful for checking character
  425. classes, some exceptions, and some useful string functions.  The
  426. constants are:
  427.  -- data of module string: digits
  428.      The string `'0123456789''.
  429.  -- data of module string: hexdigits
  430.      The string `'0123456789abcdefABCDEF''.
  431.  -- data of module string: letters
  432.      The concatenation of the strings `lowercase' and `uppercase'
  433.      described below.
  434.  -- data of module string: lowercase
  435.      The string `'abcdefghijklmnopqrstuvwxyz''.
  436.  -- data of module string: octdigits
  437.      The string `'01234567''.
  438.  -- data of module string: uppercase
  439.      The string `'ABCDEFGHIJKLMNOPQRSTUVWXYZ''.
  440.  -- data of module string: whitespace
  441.      A string containing all characters that are considered whitespace,
  442.      i.e., space, tab and newline.  This definition is used by
  443.      `split()' and `strip()'.
  444. The exceptions are:
  445.  -- exception of module string: atoi_error
  446.      Exception raised by `atoi' when a non-numeric string argument is
  447.      detected.  The exception argument is the offending string.
  448.  -- exception of module string: index_error
  449.      Exception raised by `index' when SUB is not found.  The argument
  450.      are the offending arguments to index: `(S, SUB)'.
  451. The functions are:
  452.  -- function of module string: atoi (S)
  453.      Converts a string to a number.  The string must consist of one or
  454.      more digits, optionally preceded by a sign (`+' or `-').
  455.  -- function of module string: expandtabs (S, TABSIZE)
  456.      Expand tabs in a string, i.e. replace them by one or more spaces,
  457.      depending on the current column and the given tab size.  The
  458.      column number is reset to zero after each newline occurring in
  459.      the string.  This doesn't understand other non-printing
  460.      characters or escape sequences.
  461.  -- function of module string: find (S, SUB, I)
  462.      Return the lowest index in S not smaller than I where the
  463.      substring SUB is found.  Return `-1' when SUB does not occur as a
  464.      substring of S with index at least I.  If I is omitted, it
  465.      defaults to `0'.
  466.  -- function of module string: index (S, SUB, I)
  467.      Like `index' but raise `index_error' when the substring is not
  468.      found.
  469.  -- function of module string: lower (S)
  470.      Convert letters to lower case.
  471.  -- function of module string: split (S)
  472.      Returns a list of the whitespace-delimited words of the string S.
  473.  -- function of module string: splitfields (S, SEP)
  474.      Returns a list containing the fields of the string S, using the
  475.      string SEP as a separator.  The list will have one more items
  476.      than the number of non-overlapping occurrences of the separator
  477.      in the string.  Thus, `string.splitfields(S, ' ')' is not the
  478.      same as `string.split(S)', as the latter only returns non-empty
  479.      words.  As a special case, `splitfields(S, '')' returns `[S]',
  480.      for any string S.  (See also `regsub.split()'.)
  481.  -- function of module string: join (WORDS)
  482.      Concatenate a list or tuple of words with intervening spaces.
  483.  -- function of module string: joinfields (WORDS, SEP)
  484.      Concatenate a list or tuple of words with intervening separators. 
  485.      It is always true that `string.joinfields(string.splitfields(T,
  486.      SEP), SEP)' equals T.
  487.  -- function of module string: strip (S)
  488.      Removes leading and trailing whitespace from the string S.
  489.  -- function of module string: swapcase (S)
  490.      Converts lower case letters to upper case and vice versa.
  491.  -- function of module string: upper (S)
  492.      Convert letters to upper case.
  493.  -- function of module string: ljust (S, WIDTH)
  494.  -- function of module string: rjust (S, WIDTH)
  495.  -- function of module string: center (S, WIDTH)
  496.      These functions respectively left-justify, right-justify and
  497.      center a string in a field of given width.  They return a string
  498.      that is at least WIDTH characters wide, created by padding the
  499.      string S with spaces until the given width on the right, left or
  500.      both sides.  The string is never truncated.
  501.  -- function of module string: zfill (S, WIDTH)
  502.      Pad a numeric string on the left with zero digits until the given
  503.      width is reached.  Strings starting with a sign are handled
  504.      correctly.
  505. File: python-lib.info,  Node: rand,  Next: whrandom,  Prev: string,  Up: Standard Modules
  506. Standard Module `rand'
  507. ======================
  508. This module implements a pseudo-random number generator with an
  509. interface similar to `rand()' in C.  It defines the following
  510. functions:
  511.  -- function of module rand: rand ()
  512.      Returns an integer random number in the range [0 ... 32768).
  513.  -- function of module rand: choice (S)
  514.      Returns a random element from the sequence (string, tuple or list)
  515.      S.
  516.  -- function of module rand: srand (SEED)
  517.      Initializes the random number generator with the given integral
  518.      seed.  When the module is first imported, the random number is
  519.      initialized with the current time.
  520. File: python-lib.info,  Node: whrandom,  Next: regsub,  Prev: rand,  Up: Standard Modules
  521. Standard Module `whrandom'
  522. ==========================
  523. This module implements a Wichmann-Hill pseudo-random number generator. 
  524. It defines the following functions:
  525.  -- function of module whrandom: random ()
  526.      Returns the next random floating point number in the range [0.0
  527.      ... 1.0).
  528.  -- function of module whrandom: seed (X, Y, Z)
  529.      Initializes the random number generator from the integers X, Y and
  530.      Z.  When the module is first imported, the random number is
  531.      initialized using values derived from the current time.
  532. File: python-lib.info,  Node: regsub,  Next: os,  Prev: whrandom,  Up: Standard Modules
  533. Standard Module `regsub'
  534. ========================
  535. This module defines a number of functions useful for working with
  536. regular expressions (see built-in module `regex').
  537.  -- function of module regsub: sub (PAT, REPL, STR)
  538.      Replace the first occurrence of pattern PAT in string STR by
  539.      replacement REPL.  If the pattern isn't found, the string is
  540.      returned unchanged.  The pattern may be a string or an already
  541.      compiled pattern.  The replacement may contain references
  542.      `\DIGIT' to subpatterns and escaped backslashes.
  543.  -- function of module regsub: gsub (PAT, REPL, STR)
  544.      Replace all (non-overlapping) occurrences of pattern PAT in
  545.      string STR by replacement REPL.  The same rules as for `sub()'
  546.      apply.  Empty matches for the pattern are replaced only when not
  547.      adjacent to a previous match, so e.g.  `gsub('', '-', 'abc')'
  548.      returns `'-a-b-c-''.
  549.  -- function of module regsub: split (STR, PAT)
  550.      Split the string STR in fields separated by delimiters matching
  551.      the pattern PAT, and return a list containing the fields.  Only
  552.      non-empty matches for the pattern are considered, so e.g. 
  553.      `split('a:b', ':*')' returns `['a', 'b']' and `split('abc', '')'
  554.      returns `['abc']'.
  555. File: python-lib.info,  Node: os,  Prev: regsub,  Up: Standard Modules
  556. Standard Module `os'
  557. ====================
  558. This module provides a more portable way of using operating system
  559. (OS) dependent functionality than importing an OS dependent built-in
  560. module like `posix'.
  561. When the optional built-in module `posix' is available, this module
  562. exports the same functions and data as `posix'; otherwise, it searches
  563. for an OS dependent built-in module like `mac' and exports the same
  564. functions and data as found there.  The design of all Python's
  565. built-in OS dependen modules is such that as long as the same
  566. functionality is available, it uses the same interface; e.g., the
  567. function `os.stat(FILE)' returns stat info about a FILE in a format
  568. compatible with the POSIX interface.
  569. Extensions peculiar to a particular OS are also available through the
  570. `os' module, but using them is of course a threat to portability!
  571. Note that after the first time `os' is imported, there is *no*
  572. performance penalty in using functions from `os' instead of directly
  573. from the OS dependent built-in module, so there should be *no* reason
  574. not to use `os'!
  575. In addition to whatever the correct OS dependent module exports, the
  576. following variables are always exported by `os':
  577.  -- data of module os: name
  578.      The name of the OS dependent module imported, e.g. `'posix'' or
  579.      `'mac''.
  580.  -- data of module os: path
  581.      The corresponding OS dependent standard module for pathname
  582.      operations, e.g., `posixpath' or `macpath'.  Thus, (given the
  583.      proper imports), `os.path.split(FILE)' is equivalent to but more
  584.      portable than `posixpath.split(FILE)'.
  585.  -- data of module os: curdir
  586.      The constant string used by the OS to refer to the current
  587.      directory, e.g. `'.'' for POSIX or `':'' for the Mac.
  588.  -- data of module os: pardir
  589.      The constant string used by the OS to refer to the parent
  590.      directory, e.g. `'..'' for POSIX or `'::'' for the Mac.
  591.  -- data of module os: sep
  592.      The character used by the OS to separate pathname components, e.g. 
  593.      `'/'' for POSIX or `':'' for the Mac.  Note that knowing this is
  594.      not sufficient to be able to parse or concatenate
  595.      pathnames--better use `os.path.split()' and `os.path.join()'--but
  596.      it is occasionally useful.
  597. File: python-lib.info,  Node: MOST OPERATING SYSTEMS,  Next: UNIX ONLY,  Prev: Standard Modules,  Up: Top
  598. MOST OPERATING SYSTEMS
  599. **********************
  600. * Menu:
  601. * posix::                       Built-in Module `posix'
  602. * posixpath::                   Standard Module `posixpath'
  603. * getopt::                      Standard Module `getopt'
  604. File: python-lib.info,  Node: posix,  Next: posixpath,  Up: MOST OPERATING SYSTEMS
  605. Built-in Module `posix'
  606. =======================
  607. This module provides access to operating system functionality that is
  608. standardized by the C Standard and the POSIX standard (a thinly
  609. diguised UNIX interface).  It is available in all Python versions
  610. except on the Macintosh; the MS-DOS version does not support certain
  611. functions.  The descriptions below are very terse; refer to the
  612. corresponding UNIX manual entry for more information.
  613. Errors are reported as exceptions; the usual exceptions are given for
  614. type errors, while errors reported by the system calls raise
  615. `posix.error', described below.
  616. Module `posix' defines the following data items:
  617.  -- data of module posix: environ
  618.      A dictionary representing the string environment at the time the
  619.      interpreter was started.  (Modifying this dictionary does not
  620.      affect the string environment of the interpreter.) For example,
  621.      `posix.environ['HOME']' is the pathname of your home directory,
  622.      equivalent to `getenv("HOME")' in C.
  623.  -- exception of module posix: error
  624.      This exception is raised when an POSIX function returns a
  625.      POSIX-related error (e.g., not for illegal argument types).  Its
  626.      string value is `'posix.error''.  The accompanying value is a
  627.      pair containing the numeric error code from `errno' and the
  628.      corresponding string, as would be printed by the C function
  629.      `perror()'.
  630. It defines the following functions:
  631.  -- function of module posix: chdir (PATH)
  632.      Change the current working directory to PATH.
  633.  -- function of module posix: chmod (PATH, MODE)
  634.      Change the mode of PATH to the numeric MODE.
  635.  -- function of module posix: close (FD)
  636.      Close file descriptor FD.
  637.  -- function of module posix: dup (FD)
  638.      Return a duplicate of file descriptor FD.
  639.  -- function of module posix: dup2 (FD, FD2)
  640.      Duplicate file descriptor FD to FD2, closing the latter first if
  641.      necessary.  Return `None'.
  642.  -- function of module posix: _exit (N)
  643.      Exit to the system with status N, without calling cleanup
  644.      handlers, flushing stdio buffers, etc.  (Not on MS-DOS.)
  645.      Note: the standard way to exit is `sys.exit(N)'.  `posix.exit()'
  646.      should normally only be used in the child process after a
  647.      `fork()'.
  648.  -- function of module posix: exec (PATH, ARGS)
  649.      Execute the executable PATH with argument list ARGS, replacing
  650.      the current process (i.e., the Python interpreter).  The argument
  651.      list may be a tuple or list of strings.  (Not on MS-DOS.)
  652.  -- function of module posix: fork ()
  653.      Fork a child process.  Return 0 in the child, the child's process
  654.      id in the parent.  (Not on MS-DOS.)
  655.  -- function of module posix: fstat (FD)
  656.      Return status for file descriptor FD, like `stat()'.
  657.  -- function of module posix: getcwd ()
  658.      Return a string representing the current working directory.
  659.  -- function of module posix: getegid ()
  660.      Return the current process's effective group id.  (Not on MS-DOS.)
  661.  -- function of module posix: geteuid ()
  662.      Return the current process's effective user id.  (Not on MS-DOS.)
  663.  -- function of module posix: getgid ()
  664.      Return the current process's group id.  (Not on MS-DOS.)
  665.  -- function of module posix: getpid ()
  666.      Return the current process id.  (Not on MS-DOS.)
  667.  -- function of module posix: getppid ()
  668.      Return the parent's process id.  (Not on MS-DOS.)
  669.  -- function of module posix: getuid ()
  670.      Return the current process's user id.  (Not on MS-DOS.)
  671.  -- function of module posix: kill (PID, SIG)
  672.      Kill the process PID with signal SIG.  (Not on MS-DOS.)
  673.  -- function of module posix: link (SRC, DST)
  674.      Create a hard link pointing to SRC named DST.  (Not on MS-DOS.)
  675.  -- function of module posix: listdir (PATH)
  676.      Return a list containing the names of the entries in the
  677.      directory.  The list is in arbitrary order.  It includes the
  678.      special entries `'.'' and `'..'' if they are present in the
  679.      directory.
  680.  -- function of module posix: lseek (FD, POS, HOW)
  681.      Set the current position of file descriptor FD to position POS,
  682.      modified by HOW: 0 to set the position relative to the beginning
  683.      of the file; 1 to set it relative to the current position; 2 to
  684.      set it relative to the end of the file.
  685.  -- function of module posix: lstat (PATH)
  686.      Like `stat()', but do not follow symbolic links.  (On systems
  687.      without symbolic links, this is identical to `posix.stat'.)
  688.  -- function of module posix: mkdir (PATH, MODE)
  689.      Create a directory named PATH with numeric mode MODE.
  690.  -- function of module posix: nice (INCREMENT)
  691.      Add INCR to the process' "niceness".  Return the new niceness. 
  692.      (Not on MS-DOS.)
  693.  -- function of module posix: open (FILE, FLAGS, MODE)
  694.      Open the file FILE and set various flags according to FLAGS and
  695.      possibly its mode according to MODE.  Return the file descriptor
  696.      for the newly opened file.
  697.  -- function of module posix: pipe ()
  698.      Create a pipe.  Return a pair of file descriptors `(r, w)' usable
  699.      for reading and writing, respectively.  (Not on MS-DOS.)
  700.  -- function of module posix: popen (COMMAND, MODE)
  701.      Open a pipe to or from COMMAND.  The return value is an open file
  702.      object connected to the pipe, which can be read or written
  703.      depending on whether MODE is `'r'' or `'w''.  (Not on MS-DOS.)
  704.  -- function of module posix: read (FD, N)
  705.      Read at most N bytes from file descriptor FD.  Return a string
  706.      containing the bytes read.
  707.  -- function of module posix: readlink (PATH)
  708.      Return a string representing the path to which the symbolic link
  709.      points.  (On systems without symbolic links, this always raises
  710.      `posix.error'.)
  711.  -- function of module posix: rename (SRC, DST)
  712.      Rename the file or directory SRC to DST.
  713.  -- function of module posix: rmdir (PATH)
  714.      Remove the directory PATH.
  715.  -- function of module posix: stat (PATH)
  716.      Perform a *stat* system call on the given path.  The return value
  717.      is a tuple of at least 10 integers giving the most important (and
  718.      portable) members of the *stat* structure, in the order `st_mode',
  719.      `st_ino', `st_dev', `st_nlink', `st_uid', `st_gid', `st_size',
  720.      `st_atime', `st_mtime', `st_ctime'.  More items may be added at
  721.      the end by some implementations.  (On MS-DOS, some items are
  722.      filled with dummy values.)
  723.      Note: The standard module `stat' defines functions and constants
  724.      that are useful for extracting information from a stat structure.
  725.  -- function of module posix: symlink (SRC, DST)
  726.      Create a symbolic link pointing to SRC named DST.  (On systems
  727.      without symbolic links, this always raises `posix.error'.)
  728.  -- function of module posix: system (COMMAND)
  729.      Execute the command (a string) in a subshell.  This is
  730.      implemented by calling the Standard C function `system()', and
  731.      has the same limitations.  Changes to `posix.environ',
  732.      `sys.stdin' etc. are not reflected in the environment of the
  733.      executed command.  The return value is the exit status of the
  734.      process as returned by Standard C `system()'.
  735.  -- function of module posix: times ()
  736.      Return a 4-tuple of floating point numbers indicating accumulated
  737.      CPU times, in seconds.  The items are: user time, system time,
  738.      children's user time, and children's system time, in that order. 
  739.      See the UNIX manual page times(2).  (Not on MS-DOS.)
  740.  -- function of module posix: umask (MASK)
  741.      Set the current numeric umask and returns the previous umask. 
  742.      (Not on MS-DOS.)
  743.  -- function of module posix: uname ()
  744.      Return a 5-tuple containing information identifying the current
  745.      operating system.  The tuple contains 5 strings: `(SYSNAME,
  746.      NODENAME, RELEASE, VERSION, MACHINE)'.  Some systems truncate the
  747.      nodename to 8 characters or to the leading component; an better
  748.      way to get the hostname is `socket.gethostname()'.  (Not on
  749.      MS-DOS, nor on older UNIX systems.)
  750.  -- function of module posix: unlink (PATH)
  751.      Unlink PATH.
  752.  -- function of module posix: utime (PATH, (ATIME, MTIME))
  753.      Set the access and modified time of the file to the given values. 
  754.      (The second argument is a tuple of two items.)
  755.  -- function of module posix: wait ()
  756.      Wait for completion of a child process, and return a tuple
  757.      containing its pid and exit status indication (encoded as by
  758.      UNIX).  (Not on MS-DOS.)
  759.  -- function of module posix: waitpid (PID, OPTIONS)
  760.      Wait for completion of a child process given by proces id, and
  761.      return a tuple containing its pid and exit status indication
  762.      (encoded as by UNIX).  The semantics of the call are affected by
  763.      the value of the integer options, which should be 0 for normal
  764.      operation.  (If the system does not support waitpid(), this
  765.      always raises `posix.error'.  Not on MS-DOS.)
  766.  -- function of module posix: write (FD, STR)
  767.      Write the string STR to file descriptor fd.  Return the number of
  768.      bytes actually written.
  769. File: python-lib.info,  Node: posixpath,  Next: getopt,  Prev: posix,  Up: MOST OPERATING SYSTEMS
  770. Standard Module `posixpath'
  771. ===========================
  772. This module implements some useful functions on POSIX pathnames.
  773.  -- function of module posixpath: basename (P)
  774.      Return the base name of pathname P.  This is the second half of
  775.      the pair returned by `posixpath.split(P)'.
  776.  -- function of module posixpath: commonprefix (LIST)
  777.      Return the longest string that is a prefix of all strings in LIST. 
  778.      If LIST is empty, return the empty string (`''').
  779.  -- function of module posixpath: exists (P)
  780.      Return true if P refers to an existing path.
  781.  -- function of module posixpath: expanduser (P)
  782.      Return the argument with an initial component of `~' or `~USER'
  783.      replaced by that USER's home directory.  An initial `~' is
  784.      replaced by the environment variable `$HOME'; an initial `~USER'
  785.      is looked up in the password directory through the built-in
  786.      module `pwd'.  If the expansion fails, or if the path does not
  787.      begin with a tilde, the path is returned unchanged.
  788.  -- function of module posixpath: isabs (P)
  789.      Return true if P is an absolute pathname (begins with a slash).
  790.  -- function of module posixpath: isfile (P)
  791.      Return true if P is an existing regular file.  This follows
  792.      symbolic links, so both islink() and isfile() can be true for the
  793.      same path.
  794.  -- function of module posixpath: isdir (P)
  795.      Return true if P is an existing directory.  This follows symbolic
  796.      links, so both islink() and isdir() can be true for the same path.
  797.  -- function of module posixpath: islink (P)
  798.      Return true if P refers to a directory entry that is a symbolic
  799.      link.  Always false if symbolic links are not supported.
  800.  -- function of module posixpath: ismount (P)
  801.      Return true if P is a mount point.  (This currently checks whether
  802.      `P/..' is on a different device as P or whether `P/..' and P
  803.      point to the same i-node on the same device -- is this test
  804.      correct for all UNIX and POSIX variants?)
  805.  -- function of module posixpath: join (P, Q)
  806.      Join the paths P and Q intelligently: If Q is an absolute path,
  807.      the return value is Q.  Otherwise, the concatenation of P and Q
  808.      is returned, with a slash (`'/'') inserted unless P is empty or
  809.      ends in a slash.
  810.  -- function of module posixpath: normcase (P)
  811.      Normalize the case of a pathname.  This returns the path
  812.      unchanged; however, a similar function in `macpath' converts
  813.      upper case to lower case.
  814.  -- function of module posixpath: samefile (P, Q)
  815.      Return true if both pathname arguments refer to the same file or
  816.      directory (as indicated by device number and i-node number). 
  817.      Raise an exception if a stat call on either pathname fails.
  818.  -- function of module posixpath: split (P)
  819.      Split the pathname P in a pair `(HEAD, TAIL)', where TAIL is the
  820.      last pathname component and HEAD is everything leading up to
  821.      that.  If P ends in a slash (except if it is the root), the
  822.      trailing slash is removed and the operation applied to the
  823.      result; otherwise, `join(HEAD, TAIL)' equals P.  The TAIL part
  824.      never contains a slash.  Some boundary cases: if P is the root,
  825.      HEAD equals P and TAIL is empty; if P is empty, both HEAD and
  826.      TAIL are empty; if P contains no slash, HEAD is empty and TAIL
  827.      equals P.
  828.  -- function of module posixpath: splitext (P)
  829.      Split the pathname P in a pair `(ROOT, EXT)' such that `ROOT +
  830.      EXT == P', the last component of ROOT contains no periods, and
  831.      EXT is empty or begins with a period.
  832.  -- function of module posixpath: walk (P, VISIT, ARG)
  833.      Calls the function VISIT with arguments `(ARG, DIRNAME, NAMES)'
  834.      for each directory in the directory tree rooted at P (including P
  835.      itself, if it is a directory).  The argument DIRNAME specifies
  836.      the visited directory, the argument NAMES lists the files in the
  837.      directory (gotten from `posix.listdir(DIRNAME)').  The VISIT
  838.      function may modify NAMES to influence the set of directories
  839.      visited below DIRNAME, e.g., to avoid visiting certain parts of
  840.      the tree.  (The object referred to by NAMES must be modified in
  841.      place, using `del' or slice assignment.)
  842. File: python-lib.info,  Node: getopt,  Prev: posixpath,  Up: MOST OPERATING SYSTEMS
  843. Standard Module `getopt'
  844. ========================
  845. This module helps scripts to parse the command line arguments in
  846. `sys.argv'.  It uses the same conventions as the UNIX `getopt()'
  847. function.  It defines the function `getopt.getopt(args, options)' and
  848. the exception `getopt.error'.
  849. The first argument to `getopt()' is the argument list passed to the
  850. script with its first element chopped off (i.e., `sys.argv[1:]').  The
  851. second argument is the string of option letters that the script wants
  852. to recognize, with options that require an argument followed by a
  853. colon (i.e., the same format that UNIX `getopt()' uses).  The return
  854. value consists of two elements: the first is a list of
  855. option-and-value pairs; the second is the list of program arguments
  856. left after the option list was stripped (this is a trailing slice of
  857. the first argument).  Each option-and-value pair returned has the
  858. option as its first element, prefixed with a hyphen (e.g., `'-x''),
  859. and the option argument as its second element, or an empty string if
  860. the option has no argument.  The options occur in the list in the same
  861. order in which they were found, thus allowing multiple occurrences. 
  862. Example:
  863.      >>> import getopt, string
  864.      >>> args = string.split('-a -b -cfoo -d bar a1 a2')
  865.      >>> args
  866.      ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
  867.      >>> optlist, args = getopt.getopt(args, 'abc:d:')
  868.      >>> optlist
  869.      [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
  870.      >>> args
  871.      ['a1', 'a2']
  872.      >>>
  873. The exception `getopt.error = 'getopt error'' is raised when an
  874. unrecognized option is found in the argument list or when an option
  875. requiring an argument is given none.  The argument to the exception is
  876. a string indicating the cause of the error.
  877. File: python-lib.info,  Node: UNIX ONLY,  Next: AMOEBA ONLY,  Prev: MOST OPERATING SYSTEMS,  Up: Top
  878. UNIX ONLY
  879. *********
  880. * Menu:
  881. * pwd::                         Built-in Module `pwd'
  882. * grp::                         Built-in Module `grp'
  883. * socket::                      Built-in Module `socket'
  884. * select::                      Built-in module `select'
  885. * dbm::                         Built-in Module `dbm'
  886. * thread::                      Built-in Module `thread'
  887. File: python-lib.info,  Node: pwd,  Next: grp,  Up: UNIX ONLY
  888. Built-in Module `pwd'
  889. =====================
  890. This module provides access to the UNIX password database.  It is
  891. available on all UNIX versions.
  892. Password database entries are reported as 7-tuples containing the
  893. following items from the password database (see `<pwd.h>'), in order:
  894. `pw_name', `pw_passwd', `pw_uid', `pw_gid', `pw_gecos', `pw_dir',
  895. `pw_shell'.  The uid and gid items are integers, all others are
  896. strings.  An exception is raised if the entry asked for cannot be
  897. found.
  898. It defines the following items:
  899.  -- function of module pwd: getpwuid (UID)
  900.      Return the password database entry for the given numeric user ID.
  901.  -- function of module pwd: getpwnam (NAME)
  902.      Return the password database entry for the given user name.
  903.  -- function of module pwd: getpwall ()
  904.      Return a list of all available password database entries, in
  905.      arbitrary order.
  906. File: python-lib.info,  Node: grp,  Next: socket,  Prev: pwd,  Up: UNIX ONLY
  907. Built-in Module `grp'
  908. =====================
  909. This module provides access to the UNIX group database.  It is
  910. available on all UNIX versions.
  911. Group database entries are reported as 4-tuples containing the
  912. following items from the group database (see `<grp.h>'), in order:
  913. `gr_name', `gr_passwd', `gr_gid', `gr_mem'.  The gid is an integer,
  914. name and password are strings, and the member list is a list of
  915. strings.  (Note that most users are not explicitly listed as members
  916. of the group(s) they are in.) An exception is raised if the entry
  917. asked for cannot be found.
  918. It defines the following items:
  919.  -- function of module grp: getgrgid (GID)
  920.      Return the group database entry for the given numeric group ID.
  921.  -- function of module grp: getgrnam (NAME)
  922.      Return the group database entry for the given group name.
  923.  -- function of module grp: getgrall ()
  924.      Return a list of all available group entries entries, in
  925.      arbitrary order.
  926.